Appendix B - Nexus Library Query Tags
Request messages that allow a custom query of the music library all use the same query tag set. This allows you to specify the categories to search, search filters, and sort keys. The tag can contain any or all of these sections:
<query> [<categories> <category [id="1"] [code="A"]/> </categories>] [<filters> <filter [type="fieldId|fieldName"] target="Artist" operator="contains" value="love"/> </filters>] [<sortKeys> <sortKey [type="fieldId|fieldName"] target="Artist" order="asc|desc"/> </sortKeys>] [<properties> <property name="propname">value</property> </properties>] </query>
categories - Include one category tag for each category you wish to include in the search. You may use the id attribute to specify a category Id number, or the code attribute to specify the user-defined code for a category. You can obtain a list of available categories with the getCategories command. You can also use a code value of * to search the entire library, and ? to search the uncategorized songs. Note that all categories are searched when the categories section is omitted. Should you list a category that does not exist, no results will be returned.
filters - Include one filter tag for each search filter you wish to define. You can specify which field to filter on using an Id code or text name. You can specify which type you’ve used in the type attribute and the actual code or id in the target attribute. If the type attribute is not included, a best-guess will be made based on the target attribute entry. You can obtain a list of available fields with the getFieldList command. With MusicMaster PRO 7.0.09, if you are filtering on Add Date or Edit Date, you can include both the date and time when filtering. The operator attribute specifies the type of search to perform on this field and the value attribute defines the value you search for. Please note that each type of field supports a specific subset of the available operators. These are the valid operators that you may use:
| OPERATOR | MEANING | SUPPORTED FIELD TYPE(S) |
|---|---|---|
| x.. or beginswith | Field begins with | Text, Keyword, Memo, Attribute In-Out/Combo |
| Blank | Field is blank | All except Boolean |
| ..x.. or contains | Field contains | Text, Keyword, Memo |
| Containsall | Field contains all of | Attribute Multiple |
| Containsany | Field contains any of | All Attribute types |
| Containsonly | Field contains only | Attribute Multiple |
| ..x or endswith | Field ends with | Text, Keyword, Memo, Attribute In-Out/Combo |
| = or equals | Field equals | All except Boolean |
| =0= or false | Field is False | Boolean only |
| > or greaterthan | Field value greater than | Text, Keyword, Numeric, Date, Time, Runtime |
| >= or greaterorequal | Field value greater than or equal to | Text, Keyword, Numeric, Date, Time, Runtime |
| Notrivia | Has No Trivia | Keyword, Song |
| Hastrivia | Has Trivia | Keyword, Song |
| < or lessthan | Field value less than | Text, Keyword, Numeric, Date, Time, Runtime |
| <= or lessorequal | Field value less than or equal to | Text, Keyword, Numeric, Date, Time, Runtime |
| /x.. or notbeginswith | Field does not begin with | Text, Keyword, Memo, Attribute In-Out/Combo |
| Notblank | Field is not blank | All except Boolean |
| /..x.. or not contains | Field does not contain | Text, Keyword, Memo |
| Notcontainsall | Field does not contain all of | Attribute Multiple |
| Notcontainsany | Field does not contain any of | All Attribute types |
| Notcontainsonly | Field does not contain only | Attribute Multiple |
| /..x or notendswith | Fields does not end with | Text, Keyword, Memo, Attribute In-Out/Combo |
| /= or notequal | Field does not equal | All except Boolean |
| Notoverall | Field overall value is not | Attribute Combo |
| Overall | Field overall value is | Attribute Combo |
| =1= or true | Field is True | Boolean only |
| ~ or closeto | Field value is close to | Runtime |
| /~ or notcloseto |
Field value not close to [Added in 4.0sr24] |
Runtime |
sortKeys - Include one sortKey tag for each sort level you wish to define. You can specify which field to filter on using an Id code or text name. You can specify which type you’ve used in the type attribute and the actual code or id in the target attribute. If the type attribute is not included, a best-guess will be made based on the target attribute entry. You can obtain a list of available fields with the command. Note that we plan to support some special non-song field type values for search filters and sort keys in the future, which is why we’ve used this type of syntax. The order attribute defines the sort order and can be specified as asc or desc.
properties – Include one property tag for each query property you wish to specify.
filterMatchMode – The filterMatchMode property determines how songs will match when more than one query filter has been specified. By default, AND mode is used so songs must match all of the specified query filters. You can specify AND mode in this property by setting this value to ‘all’. You can also change it to use OR mode where any one of your filters must match by setting this value to ‘any’:
<properties> <property name="filterMatchMode">[any][all]</property> </properties>
firstRec – firstRec (and maxRecs) can be used to retrieve a long list of songs in pages. These properties allow you to specify the first record from the list to retrieve, and the total number you would like to get. You can perform the same query multiple times with different values to get the list in pieces.
maxRecs – maxRecs (and firstRec) can be used to retrieve a long list of songs in pages. These properties allow you to specify the first record from the list to retrieve, and the total number you would like to get. You can perform the same query multiple times with different values to get the list in pieces. [Note: available in MusicMaster PRO 4.0sr19 and later only]
<properties> <property name="firstRec">1</property> <property name="maxRecs">25</property> </properties>